Introduction

IBM Sametime offers a wide range of real-time collaborative capabilities such as instant messaging and Web meetings, including audio and video conferencing and telephony integration.

In this paper we explain how to set up an Eclipse development environment to work with Lotus Symphony, then we write a simple plug-in to add an icon to the Symphony toolbar, and finally we will show how to use the Sametime JSTHelper toolkit to allow instant sharing of the Symphony document being edited when that button is clicked.

The specific case of instant sharing is illustrated further, but the reader can then apply the same integration pattern for other existing applications and Sametime capabilities.

Setting up the environment

In this section, we explain how to set up the development environment to write plug-ins for Lotus Symphony and how to configure IBM Sametime to enable the Sametime Advanced Instant Share feature and the Sametime JSTHelper toolkit.

Installing Symphony 3.0 and Eclipse

As a prerequisite you must have Lotus Symphony 3.0 and the latest version of the Sametime client (8.5.2) installed on the workstation where the development is done. Symphony 3.0 is free and can be downloaded from the Lotus Symphony software home page.

For the purpose of this article, we will use Eclipse 3.4.2 as a development environment. The Eclipse 3.4.2 Software Development Kit (SDK) can be downloaded and installed from the eclipse project archived downloads Web site.

Installing the development toolkits

Once Eclipse is installed, we need to install the Lotus Expeditor toolkit 6.2.1 and the Lotus Symphony developer toolkit.

Follow these steps to install the Lotus Expeditor toolkit 6.2.1:

1. Download the toolkit from the Lotus downloads page and unzip it into a directory on your workstation (let’s assume C:\Expeditor, for the purpose of this article).
2. Start the Eclipse Integrated Development Environment (IDE) and from the menu select Help – Software Updates.
3. Select the Available software tab and then “Add Site, Local,” and point to the C:\Expeditor\Expeditor_Toolkit_Install directory. Click OK.
4. Select all the available features from the checkboxes and then click Install.
5. Click Next, agree to the Licensing terms, and then click Next.
6. Click Finish, and then click No when offered to restart the IDE and close it instead.

Follow these steps to install the Symphony 3.0 developer toolkit:

1. Download the toolkit from the Symphony software developers page and unzip it in a directory on your workstation (let’s assume C:\Symphony_sdk, for our purposes).
2. Launch Symphony and enable the “My Widgets” panel by selecting the File – Preferences – Widgets from the menu.
3. Select “Show Widget Toolbar and the My Widgets Sidebar panel.”
4. Drag and drop into the My Widgets panel the following file: C:\Symphony_sdk\ update_sites\ development_enablement_updatesite.zip
5. Accept the License agreement terms and click Finish.
6. Restart Lotus Symphony and then close it.
7. Start the Eclipse IDE and from the menu select Help – Software Updates.
8. Select the Available software tab then “Add Site, Archive,” and point to the C:\Symphony_sdk\ update_sites\ toolkit_configuration_updatesite.zip file. Click OK.
9. Select all the available features from the checkboxes and then click Install.
10. Click Next, agree to the Licensing terms, and then click Next. Click Finish and then restart the IDE.

Configuring the Eclipse IDE

Follow these steps to configure the Eclipse IDE for Symphony plug-in development:

1. Bring up the Lotus Expeditor Toolkit Configuration window (see figure 1); if it is not showing when you start Eclipse, select Window – Preferences from the Eclipse menu, select “Client Service”, and click the Configure button.
2. In the Test Environment drop-down list, select Lotus Symphony.
3. In the Target Location field, select the framework\rcp\eclipse directory under the Symphony installation directory (for example, C:\Program Files\IBM\Lotus\Symphony\framework\rcp\eclipse)
4. Leave the other fields as is, and click OK.

Figure 1. Lotus Expeditor Toolkit Configuration window



Your Eclipse environment is now configured to develop Lotus Symphony plug-ins.

Configuring the Sametime client

It is assumed that you have the Sametime 8.5.2 standard executable and you installed it locally, using the default options of the installation wizard.

1. After the installation ends, navigate to C:\Program Files\IBM\Lotus\Sametime Connect\rcp and edit the plugin_customization.ini file to add support for Sametime Advanced features (such as instant sharing), making sure the following property is set correctly:

2. Then, to enable the Microbroker (the component that allows the Sametime client to communicate with external applications using messaging) make sure you have the following property set correctly:

3. If these properties are not present, then add them; or, if they are present but set to a different value, correct the value. Restart the Sametime client.

Developing a plug-in to add a new action to the toolbar

In this section, we show how to create an Eclipse plug-in to extend the Symphony toolbar by adding a button to it.

Creating the plug-in project and the action extension

Use the following steps to create the Eclipse plug-in development project and the actionSet extension to extend the Symphony toolbar:

1. In Eclipse, create a plug-in project, using File – New – Project – Plug-in project.
2. Give a name to your new project (such as com.ibm.productivity.tools.samples.sharing)
3. In the Extensions tab, click Add, and in the Extension Point filter field, type org.eclipse.ui.actionsSet. Click Finish
4. Switch to the plugin.xml tab and edit the extension XML element, adding the actionSet sub-element in listing 1 inside the extension element.

Listing 1. actionSet subelement

Handling the action

Now we write the Java^TM code that will handle the new action we have just created:

1. Under the project folder, create a new folder called “icons” and inside place the .jpg image for the icon (found in the accompanying projects.zip archive file, which contains the source code of the projects developed throughout this article).
2. In the src folder create a new package com.ibm.productivity.tools.samples.sharing.actions and define a new class SharingAction.java that implements the IWorkbenchWindowActionDelegate interface, as shown in figure 2.

Figure 2. New Java Class window



3. In order to have a message display when the icon is clicked, add a new field to the class:

4. In the init() method of the SharingAction class, initialize this field:

The run() method of the class will be invoked when the action is executed. For now, we only display a message, implementing the run() method like this:

Testing the newly implemented action

Let's now create a test configuration to verify our action is working as expected, using these steps:

1. In Eclipse, select the Run – Run Configurations menu; on the left-hand side, select Client Services and click the New button.
2. Enter a name (“SymphonyInstantShare”) and location of your choice for the configuration.
3. Click Apply and then Run. LotusSymphony starts, and you will see the icon for your action on the left -hand side of the homepage toolbar.
4. Click the icon; a window pops up with the title, “Information,” and the message “Hello World!”, as depicted in figure 3.

Figure 3. Running Symphony to test the action

Using the STHelper toolkit to integrate Sametime Advanced Instant Share

Instant Share is an IBM Lotus Sametime Advanced capability that allows the user to start an immediate two-way or multi-way desktop sharing session with other Sametime contacts. The participants can share all or a portion of their screen, or a specific application window, and take control of another participant’s desktop.

For more information on Instant Share, refer to the Sametime Advanced Help.

In this section we explain how to use the STHelper toolkit to add Sametime features into Lotus Symphony. We use the plug-in developed previously and change the action implementation to start a Sametime Advanced Instant Share session.

Linking the STHelper toolkit into the Symphony application

To allow Symphony to load the STHelper toolkit, we link the toolkit into the Symphony application configuration, using these steps:

1. In the Symphony installation directory, locate the framework\rcp\eclipse\links directory and create a file named “sthelper.link”.

2. Using a text editor, edit the file, pasting the following line into it:

3. In Eclipse, select Window – Preferences from the menu, select Plug-in Development\Target Platform, and then click Reload.

The Sametime STHelper toolkit will now be loaded by Symphony when it starts.

Adding STHelper toolkit dependencies to the plug-in

The next step is to define the dependencies of our plug-in:

1. In Eclipse, open the plugin.xml file, and in the Dependencies tab, add the following plug-ins (see figure 4):
Figure 4. Required dependencies to use the STHelper toolkit



You are now ready to use the JSTHelper toolkit from the action implementation.

Modifying the Symphony action to start Instant Share session

We first must add a JSTHelper member to the action implementation class. JSTHelper is the main toolkit class that exposes the Sametime functionality external applications.

1. Add a new data member of type JSTHelper to the SharingAction class and modify the init() method of the class to instantiate it (see listing 2).

Listing 2. Add new JSTHelper data member

2. To establish the connection to the Sametime client and initiate the Instant Share session, modify the run() method of the class, as shown in listing 3.

Listing 3. Modify the run() method

3. Finally, the dispose() method must be updated to release the connection to the Sametime client, if it was established during the call to the run() method (see listing 4).

Listing 4. Update dispose() method

Testing the integration

The plug-in is now complete, and it must be tested. To do this:

1. Start the Sametime client and log on.
2. In Eclipse, open the Run – Run Configurations menu, and select the SymphonyInstantShare configuration created earlier.
3. Click Run to start Lotus Symphony, and create a document, spreadsheet or presentation, or open an existing one.
4. In the toolbar, click the Instant Share button, as shown in figure 5.

Figure 5. Instant Share action button in Symphony toolbar



5. The Invite to Instant Share Session window opens (see figure 6); select one or more remote participants to add to the session by looking them up in the Name field. Click Send.

Figure 6. Invite to Instant Share Session window



6. The session initializes and, once the participants have accepted, the session starts. You see the sharing controls on your desktop, and the Symphony application window is outlined in bright orange to indicate to the user that it's being shared (see figure 7).

Figure 7. Symphony document being shared



The development of the plug-in is now complete. You have created a Symphony custom action to initiate a Sametime Instant Share session to collaborate on the Symphony document you were editing.

Packaging and distributing the plug-in

Now that you have developed the plug-in, you might want to distribute it to other people so they can install in their Symphony environment and use the instant sharing functionality. This section explains how to do this.

Creating an update site containing the feature and plug-in

The newly developed plug-in must be included in an Eclipse feature, and both of them packaged in an update site. First, we need to prepare the plug-in for deployment:

1. Open the plug-in project in Eclipse and open the build.properties file.
2. Open the Build tab and in the Binary build section, select all artifacts.

Now we need to create a feature to contain the plug-in, using these steps:

1. In Eclipse, select File – New – Project.
2. Select Feature Project in the Plug-in Development category. Click Next.
3. Enter a name for the project, such as com.ibm.productivity.tools.samples.sharingfeature.
4. In the Feature Name field, type a name for the feature, such as Sharing Feature.
5. Click Next, and select the plug-in developed earlier (i.e., com.ibm.productivity.tools.samples.sharing). Click Finish. The Sharing Feature window displays (see figure 8).

Figure 8. Creating the feature for the screen-share example



6. You can optionally enter a description in the Information tab.
7. In the Plug-ins tab, check that the plug-in is listed. Select it and click Versions.
8. In the Feature Version window, select Synchronize versions on build. Click Finish.

The created feature must now be packaged into an update site, as follows:

1. In Eclipse, select File – New – Project.
2. In the New Project menu, select Update Site Project in the Plug-in Development category. Click Next.
3. Enter a name for the project, such as com.ibm.productivity.tools.samples.sharing.updatesite. Click Finish.
4. In the Site Map tab, click Add Feature and select the feature created in the previous section (i.e., com.ibm.productivity.tools.samples.sharingfeature).
5. Click the Build All button to build the update site.

Creating the Symphony Instant Share widget

The preferred method to deploy features and plug-ins in Symphony 3 is to create a Symphony widget. We will do so for our plug-in in this section.

To be able to install the update site into the new Symphony 3 model that uses the concept of widgets, an extension.xml file must be added to the update site project:

1. In a text editor that has the ability to check the encoding type (such as Notepad++ (http://notepad-plus-plus.org), create a file called extension.xml with the content shown in listing 5.

Listing 5. extension.xml file contents

NOTE: Make sure that the encoding of the file is set to “Encode in UTF-8 without BOM”. Failure to conform to the above specified encoding type may later result in errors at the installation of the widget in Symphony.

2. Save the file in the updatesite project (see figure 9).

Figure 9. Update site project hierarchy



3. Export the updatesite project to a .zip file, making sure that the folder structure of your expanded archive looks like that shown in figure 10.

Figure 10. Widget folder hierarchy



4. Export the update site project from Eclipse into a .zip archive by right-clicking the project name and selecting Export – Archive file – Next.
5. Select “Create only selected directories” and the other options as shown in figure 11.
6. Click Finish, to complete the export and create the “sharing.zip” widget archive.

Figure 11. Exporting the update site as a .zip archive

Creating the Symphony JSTHelper widget

Recall that in figure 4 we defined the required dependencies to use the STHelper toolkit. These dependencies must be installed on the Lotus Symphony instance where we intend to deploy the screen-share widget and are provided in the form of a widget that we install by dragging and dropping into the “My Widgets” panel of Lotus Symphony.

Follow these steps to create the JSTHelper widget:

1. In Eclipse, select File – New – Project.
2. In the New Project menu, select Update Site Project in the Plug-in Development category. Click Next.
3. Enter a name for the project, such as com.ibm.collaboration.realtime.jsthelper.widget. Click Finish.
4. Create two subfolders, features and plugins.
5. Locate the jsthelper directory under the Sametime client installation directory (usually located at C:\Program Files\IBM\Lotus\Sametime Connect\jsthelper).
6. Open a DOS prompt and change directory to the jsthelper\eclipse\feature directory.
7. Run the following command line to “jar” the jsthelper feature:

8. Copy the resulting com.ibm.collaboration.realtime.jsthelper.feature_8.5.2.20110510-1632.jar file into the features directory created in step 4 above.
9. Copy the four .jar files from the jsthelper\eclipse\plugins directory into the plug-ins directory created in step 4.
10. Edit the update site site.xml file to include the following feature XML element as a child of the site XML element:

11. Create an extension file to make this update site a widget, with the content shown in listing 6.

Listing 6. Extension file content


12. Export the project as an archive (similar to that shown in figure 11) named, for example, jsthelper.zip.

Deploying/running the Instant Share widget

To do this:

1. Drop the JSTHelper widget created in the previous section into the My Widgets panel of Symphony, and accept the terms of the License agreement.
2. Since the plug-in is not signed, a warning will display; ignore it and proceed with installing.
3. You will be then prompted to restart Symphony in order to apply the changes.

At this point you are ready to install the screen-share widget:

1. Drag and drop the sharing.zip widget created previously. You will be prompted with a message saying that the plug-in is not signed.
2. Select the “Install this plug-in” option and then restart Symphony. Your Symphony UI should look like that shown in figure 12.
3. Note the two widgets installed in the My Widgets panel and the screenshare icon in the toolbar.

Figure 12. Sametime sharing feature integrated in Symphony


To run the screen-share feature:

1. Make sure that the Sametime client was previously configured to enable the Advanced features, as described in Section 2.5,“Configuring the Sametime client”.
2. Start the Sametime client and then start Symphony. You should see in Symphony’s toolbar a new icon for sceen sharing; click it to start sharing.

Conclusion

This paper has shown how you can integrate IBM Sametime with Lotus Symphony by using the STHelper Java toolkit. The toolkit supports all Eclipse-based software, so the approach used here can be extended to a variety of applications to provide Sametime integration.

The toolkit exposes a variety of Sametime features, such as presence (set & get presence status), chat, voice & telephony interaction, as well as the possibility to manipulate the Contact list.

Resources

• Refer to the projects.zip archive Download, which contains the source code of the projects developed in this article.

• To learn more about Sametime, read the Lotus Sametime home page.

• For more information on extending Sametime, including the reference for the JSTHelper toolkit, download the Lotus Sametime Software Developer Kit (SDK).

• To learn more about Symphony, consult the Lotus Symphony home page.

• For tips on extending Symphony, check the Lotus Symphony Developer home page.

About the authors

Olivier Bernin is the architect of the Sametime Office Integration project. He has previously published articles on developerWorks about IBM WebSphere Portal and IBM Sametime Advanced. You can reach him at obernin@ie.ibm.com.

Sorin Ciolofan is a Software Engineer at the Dublin Software Laboratory and is an accredited IBM IT Specialist. He has been involved in J2EE, WebSphere Portal, Eclipse plug-ins development, as well as Semantic Web projects. You can reach him at ciolofan@ie.ibm.com.